---
sidebar_position: 4
---

# Server Usage

dep-scan and cdxgen can operate in a server mode for distributed or centralized scanning. This mode exposes an HTTP API for on-demand analysis.

```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up
```

Alternatively, start the server directly:

```bash
depscan --server --server-host 127.0.0.1 --server-port 7070
```

The server listens for requests on the `/scan` endpoint. The `type` parameter is mandatory for all scan requests.

**Example: Scanning a local SBOM file**

```bash
curl --json '{"path": "/tmp/app/sbom.json", "type": "js"}' http://0.0.0.0:7070/scan
```

**Example: Scanning a remote Git repository**

```bash
curl --json '{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app", "type": "js"}' http://0.0.0.0:7070/scan -o app.vdr.json
```

**Example: Uploading an SBOM file for analysis**

```bash
curl -X POST -H 'Content-Type: multipart/form-data' -F 'file=@/tmp/app/sbom.json' http://0.0.0.0:7070/scan?type=js
```

> [!WARNING]
> The dep-scan server is designed for trusted environments. It executes build tools and analysis logic based on the provided source code or SBOM. Deploying it in an untrusted network without additional security boundaries (e.g., network segmentation, containerization, WAF) is strongly discouraged.

## Security Configuration

The server incorporates several built-in security mechanisms to mitigate common attack vectors. These are configurable via command-line arguments and environment variables.

### Host and Path Allowlisting

Access to the `/scan` endpoint can be restricted based on the client's IP address and the filesystem paths accessed during the scan. This prevents unauthorized access and limits the scope of potential path traversal or local file inclusion attacks.

**Configuration:**

-   `--allowed-hosts`: A space-separated list of IP addresses or hostnames permitted to access the server.
-   `--allowed-paths`: A space-separated list of base directories that the server is allowed to read from or write to.

```bash
depscan --server \
  --server-host 0.0.0.0 \
  --server-port 7070 \
  --allowed-hosts 10.0.1.100 10.0.1.101 \
  --allowed-paths /scan_input /scan_output
```

When a scan request includes a `path` parameter, the server resolves it to its absolute path using `realpath` and verifies that it falls under one of the specified `--allowed-paths`. Requests for paths outside this allowlist are rejected with a `403 Forbidden` response.

```
Client Request Path: /input/../secret.txt
Resolved Path:     /secret.txt
Allowed Paths:     [/scan_input, /scan_output]
Result:            Rejected (403)
```

### URL Scheme Allowlisting

When scanning projects from a remote URL (e.g., a Git repository), the server validates the URL's scheme against a predefined set. This prevents the execution of potentially unsafe protocols.

By default, the allowed schemes are `http`, `https`, `git`, `git+http`, `git+https`. This can be customized using the `DEPSCAN_SERVER_ALLOWED_GIT_SCHEMES` environment variable.

```bash
export DEPSCAN_SERVER_ALLOWED_GIT_SCHEMES="https,git+https"
```

Requests containing URLs with schemes not in this list will be rejected with a `400 Bad Request` response.

### Input Validation and Sanitization

-   **File Uploads**: Uploaded BOM files are validated for JSON structure and CycloneDX format. The file extension must be `.json`, `.cdx`, or `.bom`.
-   **Content Length**: The maximum size for incoming request bodies (including file uploads) is limited to prevent resource exhaustion. This limit is controlled internally and defaults to 100MB.
-   **Parameter Validation**: The `url` parameter is parsed to ensure its scheme is allowed.

### Security Headers

The server automatically appends common security headers to all HTTP responses to mitigate client-side vulnerabilities:

-   `X-Content-Type-Options: nosniff`
-   `X-Frame-Options: SAMEORIGIN`
-   `X-XSS-Protection: 1; mode=block`
-   `Strict-Transport-Security: max-age=31536000; includeSubDomains` (if served over HTTPS)
